home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3p / ftn / ussetlock.z / ussetlock
Encoding:
Text File  |  1998-10-30  |  10.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4. UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))                                                    UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ussetlock, uscsetlock, uswsetlock, ustestlock, usunsetlock - spinlock
  10.      routines
  11.  
  12. FFFFOOOORRRRTTTTRRRRAAAANNNN SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      iiiinnnntttteeeeggggeeeerrrr****4444 ffffuuuunnnnccccttttiiiioooonnnn uuuusssssssseeeettttlllloooocccckkkk ((((lllloooocccckkkk))))
  14.      TTTTYYYYPPPPEEEE lllloooocccckkkk
  15.  
  16.      iiiinnnntttteeeeggggeeeerrrr****4444 ffffuuuunnnnccccttttiiiioooonnnn uuuussssccccsssseeeettttlllloooocccckkkk ((((lllloooocccckkkk,,,, ssssppppiiiinnnnssss))))
  17.      TTTTYYYYPPPPEEEE lllloooocccckkkk
  18.      iiiinnnntttteeeeggggeeeerrrr****4444 ssssppppiiiinnnnssss
  19.  
  20.      iiiinnnntttteeeeggggeeeerrrr****4444 ffffuuuunnnnccccttttiiiioooonnnn uuuusssswwwwsssseeeettttlllloooocccckkkk ((((lllloooocccckkkk,,,, ssssppppiiiinnnnssss))))
  21.      TTTTYYYYPPPPEEEE lllloooocccckkkk
  22.      iiiinnnntttteeeeggggeeeerrrr****4444 ssssppppiiiinnnnssss
  23.  
  24.      iiiinnnntttteeeeggggeeeerrrr****4444 ffffuuuunnnnccccttttiiiioooonnnn uuuusssstttteeeessssttttlllloooocccckkkk ((((lllloooocccckkkk))))
  25.      TTTTYYYYPPPPEEEE lllloooocccckkkk
  26.  
  27.      iiiinnnntttteeeeggggeeeerrrr****4444 ffffuuuunnnnccccttttiiiioooonnnn uuuussssuuuunnnnsssseeeettttlllloooocccckkkk ((((lllloooocccckkkk))))
  28.      TTTTYYYYPPPPEEEE lllloooocccckkkk
  29.  
  30.                where TTTTYYYYPPPPEEEE is iiiinnnntttteeeeggggeeeerrrr****4444 in 32 bit mode, and is iiiinnnntttteeeeggggeeeerrrr****8888 in 64
  31.                bit mode.
  32.  
  33. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  34.      This set of routines provide a standard test and set facility.  If the
  35.      lock is free then it is atomically locked, and control is returned to the
  36.      caller.  If the lock is already locked, the caller either spins waiting
  37.      for the lock or gets queued.  The locks are based in user address space
  38.      thus avoiding any system call overhead in the case where the lock is
  39.      available.
  40.  
  41.      The actual algorithm used to implement these functions depends on whether
  42.      the system is a multiprocessor or a single processor.  In the
  43.      multiprocessor case, if the lock is already locked, the caller will spin
  44.      (i.e. busy wait).  The amount of time it spins depends on the function -
  45.      for _uuuu_ssss_ssss_eeee_tttt_llll_oooo_cccc_kkkk, a system chosen value is used, for _uuuu_ssss_cccc_ssss_eeee_tttt_llll_oooo_cccc_kkkk and
  46.      _uuuu_ssss_wwww_ssss_eeee_tttt_llll_oooo_cccc_kkkk the value of _s_p_i_n_s is used.  If, after _s_p_i_n_s attempts to
  47.      acquire the lock have all failed, the function will either return
  48.      (_uuuu_ssss_cccc_ssss_eeee_tttt_llll_oooo_cccc_kkkk) or yield the processor (_uuuu_ssss_ssss_eeee_tttt_llll_oooo_cccc_kkkk, or _uuuu_ssss_wwww_ssss_eeee_tttt_llll_oooo_cccc_kkkk).  The
  49.      yield is affected by calling _ssss_gggg_iiii_nnnn_aaaa_pppp(2).  After returning from yield,
  50.      _uuuu_ssss_ssss_eeee_tttt_llll_oooo_cccc_kkkk and _uuuu_ssss_wwww_ssss_eeee_tttt_llll_oooo_cccc_kkkk will again attempt to acquire the lock _s_p_i_n_s
  51.      times.  This will continue until the lock is finally acquired.  Note that
  52.      if a process spends much of its time waiting for a lock without giving up
  53.      the processor, then the total throughput of the system may be reduced.
  54.      On the other hand, by giving up the processor too quickly, there is a
  55.      longer latency between when the lock is freed and the caller obtains the
  56.      lock.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))                                                    UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))
  71.  
  72.  
  73.  
  74.      The implementation of locks on single processor systems never spin; if
  75.      the lock is unavailable the caller is atomically queued.  This queueing
  76.      operation suspends the calling process and forces a scheduling cycle.
  77.      Processes are removed from the queue in FIFO order when the lock is
  78.      released.
  79.  
  80.      The appropriate lock algorithm is selected automatically at program
  81.      startup time.  Different levels of debugging information can be requested
  82.      via uuuussssccccoooonnnnffffiiiigggg(3P).
  83.  
  84.      uuuusssssssseeeettttlllloooocccckkkk doesn't return until the lock specified by _l_o_c_k is acquired.
  85.      uuuussssccccsssseeeettttlllloooocccckkkk attempts to acquire a lock _s_p_i_n_s times, returning a 1 if the
  86.      lock was acquired, and a 0 if it was not available.  uuuusssswwwwsssseeeettttlllloooocccckkkk is
  87.      similar to uuuusssssssseeeettttlllloooocccckkkk,,,, except that the caller specifies the number of
  88.      times the lock is attempted to be acquired before the process gives up
  89.      control of the processor.  On a single processor this call is identical
  90.      with uuuusssssssseeeettttlllloooocccckkkk.  uuuusssstttteeeessssttttlllloooocccckkkk returns the instantaneous value of the lock,
  91.      a 0 if it is not locked, and a 1 if it is locked.  uuuussssuuuunnnnsssseeeettttlllloooocccckkkk releases
  92.      the lock.
  93.  
  94.      When invoked with a valid lock, uuuusssssssseeeettttlllloooocccckkkk and uuuusssswwwwsssseeeettttlllloooocccckkkk do not return
  95.      until the lock is acquired.  An invalid lock will yield unpredictable
  96.      results.
  97.  
  98.      It is allowed to call uuuussssuuuunnnnsssseeeettttlllloooocccckkkk on a lock that is either not locked or
  99.      locked by another process.  In either case, the lock will be unlocked.
  100.      Double tripping, i.e. calling a set lock function twice with the same
  101.      lock is also permissible.  The caller will block until another process
  102.      unsets the lock.
  103.  
  104.      In order to use a lock, the caller must have joined the shared arena out
  105.      of which the lock is allocated (via uuuussssiiiinnnniiiitttt(3P)), and have a file
  106.      descriptor to a uuuusssseeeemmmmaaaa(7M) device to suspend/unsuspend on.  As a
  107.      convenience, these routines will automatically do this for members of a
  108.      share group, or for related (via ffffoooorrrrkkkk(2)) processes.  This automatic
  109.      facility can generate the same errors as uuuussssiiiinnnniiiitttt(3P).  These errors will
  110.      be passed back to the caller.  If tracing is enabled (see uuuussssiiiinnnniiiitttt(3P))
  111.      then any errors will cause a message to be printed to _s_t_d_e_r_r.  To avoid
  112.      these errors and therefore not need to check for errors on every lock
  113.      call, have each process call uuuussssiiiinnnniiiitttt(3P) before using any locks.
  114.  
  115.      These locks are designed to be fast in the case where the lock is
  116.      available.  On a Challenge R4400 multiprocessor a uuuusssssssseeeettttlllloooocccckkkk, uuuunnnnsssseeeettttlllloooocccckkkk
  117.      pair takes about 500nS.
  118.  
  119.      When using debugging lock types the following debugging prints can occur.
  120.  
  121.      _D_o_u_b_l_e _t_r_i_p_p_e_d _o_n _l_o_c_k @ _0_x... _b_y _p_i_d ... will be printed when an attempt
  122.      is made to acquire a lock that is already held by the caller.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))                                                    UUUUSSSSSSSSEEEETTTTLLLLOOOOCCCCKKKK((((3333PPPP))))
  137.  
  138.  
  139.  
  140.      _U_n_l_o_c_k_i_n_g _l_o_c_k _t_h_a_t _o_t_h_e_r _p_r_o_c_e_s_s _l_o_c_k_d _l_o_c_k @ _0_x... _b_y _p_i_d ... will be
  141.      printed when an attempt is made to release a lock that is not held by the
  142.      process attempting to release it.
  143.  
  144.      _U_n_s_e_t _l_o_c_k, _b_u_t _l_o_c_k _n_o_t _l_o_c_k_e_d. _l_o_c_k @ _0_x... _p_i_d ... will be printed
  145.      when using debug software locks, and an attempt was made to unlock a lock
  146.      that was not locked.
  147.  
  148.      The following errors can occur due to misuse of a lock:
  149.  
  150.      [EBADF]        The underlying file descriptor for the lock was closed or
  151.                     re-used by the application.
  152.  
  153. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  154.      sginap(2), barrier(3P), uscas(3P), usconfig(3P), usctllock(3P),
  155.      usdumplock(3P), usfreelock(3P), usinitlock(3P), usinit(3P), uspsema(3P).
  156.      usnewlock(3P), usnewsema(3P), usema(7M).
  157.  
  158. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  159.      uuuusssssssseeeettttlllloooocccckkkk,,,, uuuusssswwwwsssseeeettttlllloooocccckkkk,,,, uuuussssccccsssseeeettttlllloooocccckkkk,,,, and uuuusssstttteeeessssttttlllloooocccckkkk will return a 1 if the
  160.      lock is acquired and a 0 if the lock is not acquired.  uuuussssuuuunnnnsssseeeettttlllloooocccckkkk always
  161.      returns 0 if successful.  On error, -1 is returned and _e_r_r_n_o is set to
  162.      indicate the error.
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.